Tech Arsenal 1/Tech Arsenal (Arsenal Computer).ISO/tek-20/kttrm100.zip/KTTERM.DOC

Text File | 1992-09-07 | 48KB | 1,085 lines

1.0)  INTRODUCTION

KTterm is based on another recent development of mine, KAMterm, which
is a full Host Mode terminal program for the Kantronics line of TNCs.
As it turned out, users with non-Kantronics TNCs wanted to take
advantage of the features built into KAMterm with other brands of TNCs.
KTterm is the result of their requests.  While this program cannot
begin to match the power offered by KAMterm, it does provide some
interesting features for non-Host Mode communications.

If you have a Kantronics TNC, and would be interested in the additional
features offered by KAMterm (see the file, kamterm.inf), please contact
me.

I've included a lot of the standard bits that you see in most terminal
programs (i.e., split-screen, scrollback buffers, logging to a file,
etc.).  I've also added a lot of things that, in my opinion, have been
seriously lacking in everything I've tried for packet terminal programs.

KTterm is designed around several basic concepts:

*) KTterm is designed to be extremely simple to operate.

*) KTterm WILL NOT MODIFY YOUR TNC's PARAMETERS UNLESS YOU ASK IT TO.

*) IF YOU CHOOSE TO DO SO, you have the ability to create startup and/or
   exit command files that will configure the TNC for you.

*) When logging to a file, KTterm will try to keep things organized by
   adding a line above any text it logs indicating who said what.

*) In some menus, if you have a mouse, the mouse can be used for those
   menus.

*) Scrollback buffers are setup for each window if memory permits.  Size
   is adjustable via configuration file (ktterm.cfg).

*) KTterm will notify you of incoming connects no matter where you
   happen to be at the time (requires that the TNC's RING parameter be
   turned on).

*) Programmable function keys --- <F1> is reserved for HELP, but
   otherwise, any of the function keys (<F1> through <F10>) can be used
   alone or in combination with <SHIFT>, <ALT>, and/or <CTRL> for your
   own macros, etc.  The limitation here is that the string is limited
   to 80 chars.

*) Macro command files --- just as you can have setup files for start
   and exit, you can send macro command files to the TNC at any time
   while running KTterm.

*) ``Brag'' files are supported, too.  You will be asked for the name of
   the file you wish to transmit.


2.0)  DISCLAIMER

KTterm is provided AS IS with no warranty, expressed, written, or
implied.  While every effort has been made to keep KTterm free of bugs,
individual systems do vary, and it is beyond the author's ability to
test KTterm in all possible system configurations.  Under no
circumstances shall KTterm's author be liable for incidental or
consequential damages that may be incurred by the performance or use of
this product.


3.0)  DISTRIBUTION

You are free to distribute UNMODIFIED copies of KTterm, providing that
all documentation, sample files, and other related files are also
distributed unmodified.  This applies ONLY to the shareware
distribution --- registered versions of KTterm, as well as the typeset
documentation, are not to be distributed, period.

KTterm may, if needed, be re-packaged by another archiving program
(e.g., ZIP, ZOO, ARJ, etc.) for distribution.  This represents the only
acceptable ``modification'' for its distribution.

Under NO circumstances is the Copyright notice within the program or its
documentation to be altered in any way or removed.


4.0)  NS16550AN/AFN SUPPORT

KTterm provides full support for the NS16550AN and NS16550AFN UARTs.
These UARTs (made by National Semiconductor), provide a much greater
degree of reliability at higher speeds (the definition of which depends
on the speed of the computer, and ranges from 4800 bps in severe cases
to 38,400 bps or higher on faster computers).

The 16550 does this in two ways.  First, it provides a 16 character
FIFO buffer, as opposed to the 1 character FIFO in older UARTs such
as the 8250.  This provides some breathing room for your program.
The second thing the 16550 does is to allow a single interrupt for
multiple characters.  In other words, with only one interrupt, a
communications program can read several characters from the port at
a time.  This substantially reduces the interrupt loading on the
computer, and thus improves performance of serial I/O.

KTterm automatically detects either the NS16550AN or NS16550AFN
if it exists, and takes advantage of the FIFO and the modified
interrupt structure described above.

Note, however, that while KTterm does support speeds up to (and
including) 115,200 bps, most TNCs currently only support speeds up
to 9600 bps.

If you do not have 16550 UART (you would know if you did --- they are
more expensive, and are not standard stock in most serial cards), and
particularly if you have a slower computer, you may run into problems
running at 9600 bps.  If you're seeing dropped characters (normally
only a problem when there is a continuous stream of incoming data),
try dropping the speed down to, say, 4800 bps or lower.  Remember to
change the speed on the TNC (this requires a reset) before changing
KTterm.

5.0)  KTterm OPERATIONS

This section will describe some operational aspects of KTterm.  These
include startup options and screen layout.

5.1)  SCREEN LAYOUT

The physical screen is divided into 2 regions.  The first is the main output
window.  This takes the majority of the screen.  The second is the local
window, which is the first place where the text you type will be echoed.
The format shouldn't be new to anyone who has used popular terminal programs
for packet radio.  The status bar in between these which indicates the
stream, who (if anyone) that stream is connected to, etc.

5.1.1)  THE SCREEN ITSELF

When you first start KTterm you will see a screen which looks
something like the following:

╔════════════════════════════════ TOP OF SCREEN ══════════════════════════════╗
║                                                                             ║
║ This is the MAIN WINDOW.  All text coming FROM the TNC is placed in this    ║
║ window, as is the local echo (if it is turned on).                          ║
║                                                                             ║
║ This window uses lines 0 through 19 on the screen.                          ║
║                                                                             ║
║                                                                             ║
║                                                                             ║
║                                                                             ║
║                                                                             ║
║                                                                             ║
║ The line below (it is only one line in the program) is line 20, which is    ║
║ the STATUS LINE.                                                            ║
───────────────────────────────────────────────────────────────────────────────
F1=HELP COM1 9600 8N1         KTterm Version 1.0          09 May 1992  12:33:37
───────────────────────────────────────────────────────────────────────────────
║                                                                             ║
║ This is the LOCAL WINDOW.  Text you type goes here.  This window uses       ║
║ lines 21 through 24 on the screen.                                          ║
║                                                                             ║
╚══════════════════════════════ BOTTOM OF SCREEN ═════════════════════════════╝


So, with that picture in mind, let's take a look at what we've got.

First, the main window contains all text coming in from the TNC for the
stream assigned to the current window.

The last window on the screen is the local window.  This is where text you
type is first echoed.  In here, you can edit a line of text to send to the
TNC before actually sending the data.  If the line exceeds 78 characters,
everything that has been typed to that point will be transmitted to the
TNC.  Word wrap is not currently implemented.

5.1.2)  THE STATUS BAR

The status window provides some information as to where you are, how things
are configured, etc.  Reading from left to right, we first see a reminder
that F1 can be used for HELP.  Next, we see that the serial port is
configured for COM1, 9600 bps, 8 data bits, No parity, and 1 stop bit.

At the far right of the status bar we have the current date and time,
according to your computer's clock.

5.1.3)  LOCAL ECHO vs. INCOMING TEXT

KTterm allows you to use a different color for locally echoed text than
that used for incoming text from the TNC.  This is defined in the
configuration file, ktterm.cfg, which is discussed later.  The default
is to use YELLOW for locally echoed text, and LIGHTBLUE for incoming
text.  These are also configured in the configuration file.

5.2)  NEW CONNECTS

KTterm will notify you of incoming connects.  This requires that the
TNC parameter RING be set to ON (the ^G characters sent from the TNC
on incoming connects are used as the indicator that the connect was not
originated by you).  Note that this parameter is not available on all
TNCs.


6.0)  KTterm COMMANDS

This section describes the commands available within KTterm.  They are
covered in order by the key that calls them (i.e., <ALT><B> will be
covered before <ALT><F>, etc.).

6.1)  [ALT][A]

This command is used to switch KTterm into and out of a special mode
in which it will immediately transmit any character you type to the
TNC.  The primary purpose for this mode is for those TNC types which
require a '*' character for auto-baud setting.  Issuing this command
again will take you out of this mode.

When you enter this mode, you will see the center portion of the status
bar go into a sort of reverse-video, i.e., the foreground and background
colors you have defined for the status bar will be reversed.

Note that when switching from normal editing mode to this special mode,
any text you have typed on the line that has not been transmitted to the
TNC will be erased.  This is done to prevent accidents, confusion, etc.,
from any leftover text reappearing at a later time.


6.2)  [ALT][B]

This command is used to transmit a ``brag file'' to the connected station.
A window will popup and ask you for the name of the file you wish to
transmit.  If this file is found, it will be transmitted just as if you
had typed the information.  If, on the other hand, it is not found,
KTterm will complain about not finding the file, and return to normal
operation.

During each phase of the file transmission, KTterm will check to see
that the transmit buffers have been cleared before proceeding to the next
part of the file.  This is to help insure that the buffers in the TNC are
not overrun by trying to send information faster than it can transmit it
to the remote station.  If the TNC's buffers fill up, and it tells your
computer to stop sending data, the buffers within KTterm will not
empty, and KTterm will wait until it can move on.

This function is not really intended for use to upload large text files
to a BBS, etc., though it could probably be used for such applications.
It is intended for short files describing your station, and does not
implement any error control with the remote station, and assumes that
if the TNC is happy, the remote end is happy.

Functionality for uploading actual files will be added when I get the
protocol specifications for file transfer programs used on packet BBS
systems.

6.3)  [ALT][C]

This command clears the screen.

6.4)  [ALT][E]

This command toggles the local echo of characters to the screen (from
KTterm, not from the TNC).  Local echo from KTterm is normally
used when the TNC is not echoing characters you type.  In its normal
operating mode, the TNC uses the ECHO command to determine whether or
not you want input echoed back.

The default value for local echo from KTterm is off.  This can be
changed from the configuration file.  This is discussed later.

6.5)  [ALT][F]

This command is used to send a macro command file to the TNC.  You will
be asked for the name of the file you wish to send to the TNC (the default
will be the name of the startup command file, if one is defined).  This
command can be used to change the TNC's configuration while running
KTterm, if desired.

The format of the macro file is the same as that for the startup and/or
exit command files, which will be discussed later.

6.6)  [ALT][G]

This command is used to call KTterm's internal QSO logger (or,
alternatively, an external logging program).  In the log function, you
will be asked for the normal items you would enter in a logbook, such
as the person's callsign, the start/end times for the QSO, the
frequency, and so on.

The internal log function for KTterm is far from elegant.  It is
primarily intended as a quick and easy way to document the QSO
information without having to switch between a note pad, a logbook, and
the keyboard.

When entering QSO log information in the internal logger, do not save
it to a file until the entry is complete.  Once you save an entry to
disk, KTterm assumes that you have completed that entry, and the next
time you access the log in that window, it will be blank.

If you wish to set a default filename for the logfile, you can do so via
the configuration file, ktterm.cfg.  This is also where you can
instruct KTterm to use an alternate logging program.  See the section on
the configuration file for more details.

6.7)  [ALT][I]

This command provides some general information about KTterm,
registration, etc.

6.8)  [ALT][K]

This command brings up a menu which allows you to change the function
key definitions.  The menu will appear in the upper left corner of the
screen, and its exact nature will vary, depending on whether or not a
mouse was detected on the system.

The items in the menu are as follows:

                ┌────────────────────────────┐
                │ F2 through F10             │
                ├────────────────────────────┤
                │ ALT F1 through ALT F10     │
                ├────────────────────────────┤
                │ CTRL F1 through CTRL F10   │
                ├────────────────────────────┤
                │ SHIFT F1 through SHIFT F10 │
                ├────────────────────────────┤
                │ Load new function key file │
                ├────────────────────────────┤
                │ Save function keys to file │
                ├────────────────────────────┤
                │ Exit                       │
                └────────────────────────────┘

The first four options allow you to change the characters that will be
sent to the TNC for the function keys themselves.  Note that plain
<F1> is not included in this list --- <F1> itself is reserved
for HELP.

The fifth option, ``Load new function key file'', allows you to load a
new set of function key definitions from a file.  You will be asked for the
name of the file, and if it exists, it will be loaded.  Function key macro
files can either be created through the program, or manually.

The sixth option, ``Save function keys to file'', allows you to save the
function key definitions you have defined to a file.  You will be asked
for the name of the file.   The results will then be stored to that file.

The last option simply exits the menu.  Pressing <ESC> will do the
same thing.

The format for the function key file will be discussed in the section
entitled FUNCTION KEY DEFINITION FORMAT.

6.9)  [ALT][L]

This command toggles logging of the current window to a file.  If logging
on the current window is not active, you will be asked for the name of
the file to log to.

KTterm will attempt to keep things organized in the log
file by indicating who said what.  For incoming text, it will indicate
that the TNC was the source, and for outgoing text, it will use the
callsign you defined (if any) in the configuration file.  If you have
not defined a callsign, it will simply use ``YOU'' to refer to you.

6.10)  [ALT][M]

This gives a quick snapshot of the amount of memory available to
KTterm on your system.

6.11)  [ALT][P]

This command allows you to change the communications parameters from
within KTterm.  You will be given the following list of options:

         ┌─────────────────────────────────────────────────┐
         │ Port [1-4]:     Port Speed:                     │
         │                                                 │
         │ KTterm uses the standard setting of No parity,  │
         │ 8 data bits, and one stop bit.  Flow control is │
         │ through full-duplex hardware flow control only. │
         └─────────────────────────────────────────────────┘

The port option selects the communications port, and valid inputs are
<1>, <2>, <3>, and <4>, for COM1, COM2, COM3, and COM4, respectively.

The port speed option is just that --- port speed.  The TNC does not
support port speeds greater than 9600 bps.  KTterm will, however,
allow speed settings up to (and including) 115,200 bps.

Parity, data bits, and stop bits are automatically set at No Parity,
8 bits per character, and 1 stop bit.  In addition, the flow control
method used is bidirectional hardware flow control.

In this mode of flow control, the CTS (Clear To Send) control line is
used to inform the computer that the TNC is ready to receive data, if
the computer has any to transmit, and the RTS (Request To Send) control
line is used by the computer to inform the TNC that it is ready to
receive data, if any is available.  These operate independently of each
other.  This mode of flow control is the preferred mode for use with
high-speed modems, etc., as it adds the ability for the computer to stop
data flow from the connected device when it is not ready.

6.12)  [ALT][R]

This command allows you to execute an external DOS command.  You will
be asked for the name of the command you wish to execute.  If you simply
press <CR>, you will simply shell out to DOS.  If you decide not to
do anything here, simply press <ESC> to abort.

6.13)  [ALT][X]

Exit KTterm.

6.14)  [ALT][Y]

This command is used to set the date/time on the TNC.  It uses the current
date and time setting on your computer.

6.15)  [F1]

View HELP SCREEN.

6.16)  [UP-ARROW]

If scrollback is enabled, and if scrollback buffers could be allocated
to the current window, this will pull up the scrollback buffer for the
current window.  Within scrollback, <PgUp>, <PgDn>, <HOME>, <END>, <UP>,
and <DOWN> will move you around in the scrollback buffer. <ESC> exits
back to KTterm's normal operation.

In addition, if you wish to save the entire scrollback buffer to a file,
press <S>.  KTterm will then ask you for the filename that you wish to
save the buffer to.  Press <ESC> instead of entering a filename to abort
this operation.


7.0)  THE CONFIGURATION FILE

KTterm uses a configuration file called ktterm.cfg, which allows you to
change most aspects of its configuration.  This file must exist,
however, it need not have all configuration options in it (or any of
them, for that matter).  Any options which are not set within this file
simply revert to their default values.  If the file is not found at all,
the system will create one for you with only the communications
parameters.

Within the configuration file, anything following a '#' character is
treated as a comment, blank lines will be ignored, and commands within
the file are not case-sensitive.  Only one command is allowed per line
in the file.  In the examples shown below (and in the sample
configuration file), a colon follows the field name --- this is
optional, and is included for readability only.  KTterm ignores this
completely.

Throughout this section, example commands will be represented as:

         INITFILE:  startup.kam

There may be several commands grouped together, but the groups of commands
(or the command) will have a blank space above and below it, and will be
indented.  If KTterm does not understand the input in any line, it will
advise you of this, and tell you the offending line number within the
configuration file.

7.1)  GENERAL OPTIONS

There are several types of options which may be set from the configuration
file.  This section will cover those which are general in nature, and don't
apply to any specific grouping.

7.1.1)  CAPBUFF

CAPBUFF is the size of the scrollback buffer for EACH WINDOW.  Take care
when increasing this number --- remember that each stream will have this
allocated to it, and that eats memory.  I suggest you start with the
default (100 lines) and gradually increase.  If a window is opened, and
there isn't room to allocate this number of lines, that window will not
have a scrollback buffer, but will be opened (provided there is enough
memory left to do so).

Here are some sizes for 100 line increments of the scrollback buffer (note
that there is clearly a pattern here):

      0 lines:  scrollback disabled
    100 lines:  18,400 bytes per active window
    200 lines:  28,400 bytes
    300 lines:  38,400 bytes
     ......      .......
    800 lines:  88,400 bytes

The example below sets the scrollback buffer size to 200 lines.

         CAPBUFF: 200

7.1.2)  INITFILE and EXITFILE

These options set the filenames for the optional command (macro) files to
be sent to the TNC when starting and exiting KTterm.  In the following
example, when KTterm is loaded, it will transmit all commands in the
file called startup.kam to the TNC, and right before exiting, will do
the same for the file finish.kam.

         INITFILE:  startup.kam
         EXITFILE:  finish.kam

The filenames can be anything you choose, provided of course that it is a
legal dos filename, and that the total length of the path/filename does not
exceed 80 characters.  The format for these files will be covered in the
section called FORMAT FOR INIT/EXIT COMMAND FILES.

7.1.3)  QSO LOG OPTIONS

There are several options which can be used to customize the operation
of the QSO logging functionality in KTterm.  These include setting a
default file to log information to, as well as setting up an external
logging program.

The first option is LOGFILE.  This sets the default filename that KTterm
will use when logging QSOs to a file.  You will still be asked for a
filename, and can choose an alternate file if you so desire.  This is
optional, and if this is not found in your configuration file, KTterm
will simply present a blank field when asking for the filename.

In the following example, the default filename to use for manually
entered logs is ktterm.log.

         LOGFILE: ktterm.log

In addition to these options, if you wish to use an external logging
program, you would identify it to KTterm by using the LOGGER option.
With this option, when you press <ALT><G>, you will execute the external
logging program, and when you exit from it, you will return to KTterm.
If you want KTterm to check with you before calling the external logging
program (e.g., if you sometimes use the internal logger), you can use
the ASKLOGGER option.  If ASKLOGGER is not used in your configuration
file, KTterm will run the external logging program every time you press
<ALT><G>.

In the following example, the external logging program is called by the
command ``mylogger logfile.txt'' and we do want KTterm to ask before
calling the external logger.

         LOGGER: mylogger logfile.txt
         ASKLOGGER: YES

7.1.4)  MORSESPEED

KTterm uses Morse code for a few minor status messages and error
messages.  This option allows you to determine the code speed at which
Morse code messages will be sent from within KTterm.  The default is 20
WPM.  If this parameter is set to 0 (zero) words per minute, Morse
messages will be disabled.

The example below shows the default setting of 20 WPM:

         MORSESPEED: 20

NOTE:  According to the documentation for Turbo C++, the functions used
for determining the delays used in generating the Morse code messages
do not vary with the CPU speed of the computer the program is run on.
Tests run on multiple computers have verified this, however, if you should
happen to find this to be in error, you may need to experiment a bit.

7.1.5)  MORSETONE

This option allows you to change the frequency of the tones used for
Morse code messages.  The default is 600 Hz, as represented in the
example below:

         MORSETONE: 600

7.1.6)  MYCALL

MYCALL is the callsign that will be used for logging to a file. This does
not affect the value in the TNC in any way.  The example below sets MYCALL
to N5IAL.

         MYCALL: N5IAL

7.1.7)  NORMALECHO

NORMALECHO is used to determine if KTterm should default to echoing
text locally.  The value for this must be either 1 for on or 0 (zero)
for off.

The default for is NOT to echo text locally.  The example shown below
illustrate how this parameter would be set if it were included in the
startup file.

         NORMALECHO: 0

7.1.8)  MARGINBELL

If you choose to do so, you can activate a margin bell that will sound
when you reach the specified number of characters from the left margin
(similar to the margin bell on actual mechanical typewriters).  The
default option is for this to be turned off, and if nothing is setup
in the configuration file, there will be no bell.  If, however, you wish
to set the margin bell to sound at a given column, you would setup
something like the example below, which assumes you want the bell to
sound 5 spaces from the right margin (the right margin is at column 78,
therefore, you would want it to sound when you hit column 73):

         MARGINBELL:  73

7.2)  COMMUNICATIONS PARAMETERS

This section discusses the communications parameters that can be set from
the configuration file.

7.2.1)  PORTSPEED

PORTSPEED sets the default serial port speed which KTterm will use, and
must be one of 1200, 2400, 4800, or 9600.  As this is being written, the
TNC does not allow port speeds higher than 9600 bps.  The example below
shows the default setting, 9600 bps, and how it would be set in the file.

         PORTSPEED: 9600

7.2.2)  COMMPORT

COMMPORT sets the default serial port which KTterm will use, and must be
one of 1, 2, 3, or 4, for COM1 through COM4, respectively.  In the example
below, COM1 (the default) is selected.

         COMMPORT: 1

7.3)  COLOR SETTINGS

COLOR commands take exactly 2 arguments, and they must be in the right
order.  The first argument is the parameter which we wish to associate
the color with, and the second is the color itself.

A program is included which dumps all color combinations to the screen and
identifies the foreground and background colors in effect at that time.
Use this to see how different color combinations look, and decide what you
like/don't like.

MONOCHROME USERS:  The windowing library used with this program is smart
enough to know that you have a monochrome monitor, and does not use the
majority of these colors.  Depending on what combinations you select, it
will set things up to either do normal, reverse, or high-intensity video.

Choices for colors are as follows:

         BLACK         DARKGRAY
         BLUE          LIGHTBLUE
         GREEN         LIGHTGREEN
         CYAN          LIGHTCYAN
         RED           LIGHTRED
         MAGENTA       LIGHTMAGENTA
         BROWN         YELLOW
         LIGHTGRAY     WHITE

NOTE:  If the BACKGROUND color is set to anything in the second column
(DARKGRAY through WHITE), the foreground will be flashing.  This is true
for both color and monochrome monitors.

The first set of color parameters deal with the colors assigned to the
3 key areas of the screen in normal operations (i.e., not in a menu, etc.).
The second set of color parameters deal with the colors used for popup
windows, menus, text entry (e.g., when you are asked for a filename), and
so on.  These are shown in the following tables.

    ╔═════════════════════════════════════════════════════════════════╗
    ║          Screen Colors for Normal Operations                    ║
    ╠══════════════════════╤══════════════════════════════════════════╣
    ║  STATFG              │  STATUS LINE foreground                  ║
    ╟──────────────────────┼──────────────────────────────────────────╢
    ║  STATBG              │  STATUS LINE background                  ║
    ╟──────────────────────┼──────────────────────────────────────────╢
    ║  LOCALFG             │  LOCAL WINDOW foreground                 ║
    ╟──────────────────────┼──────────────────────────────────────────╢
    ║  LOCALBG             │  LOCAL WINDOW background                 ║
    ╟──────────────────────┼──────────────────────────────────────────╢
    ║  MAINFG              │  MAIN COMMAND WINDOW foreground          ║
    ╟──────────────────────┼──────────────────────────────────────────╢
    ║  MAINBG              │  MAIN COMMAND WINDOW background          ║
    ╟──────────────────────┼──────────────────────────────────────────╢
    ║  ECHOFG              │  local echo foreground (any window)      ║
    ╟──────────────────────┼──────────────────────────────────────────╢
    ║  ECHOBG              │  local echo background (any window)      ║
    ╚══════════════════════╧══════════════════════════════════════════╝

╔════════════════════════════════════════════════════════════════════════════╗
║                     Popup Menu/Window Colors                               ║
╠═══════════════════════════╤════════════════════════════════════════════════╣
║  POPUPFG                  │ popup window foreground                        ║
╟───────────────────────────┼────────────────────────────────────────────────╢
║  POPUPBG                  │ popup window background                        ║
╟───────────────────────────┼────────────────────────────────────────────────╢
║  HELPFG                   │ help screen foreground                         ║
╟───────────────────────────┼────────────────────────────────────────────────╢
║  HELPBG                   │ help screen background                         ║
╟───────────────────────────┼────────────────────────────────────────────────╢
║  SBFG                     │ scrollback screen foreground                   ║
╟───────────────────────────┼────────────────────────────────────────────────╢
║  SBBG                     │ scrollback screen background                   ║
╟───────────────────────────┼────────────────────────────────────────────────╢
║  MENUFG                   │ menu foreground                                ║
╟───────────────────────────┼────────────────────────────────────────────────╢
║  MENUBG                   │ menu background                                ║
╟───────────────────────────┼────────────────────────────────────────────────╢
║  MENUBDRFG                │ menu border foreground                         ║
╟───────────────────────────┼────────────────────────────────────────────────╢
║  MENUBDRBG                │ menu border background                         ║
╟───────────────────────────┼────────────────────────────────────────────────╢
║  MENUSELFG                │ menu selected item foreground                  ║
╟───────────────────────────┼────────────────────────────────────────────────╢
║  MENUSELBG                │ menu selected item background                  ║
╟───────────────────────────┼────────────────────────────────────────────────╢
║  MENUFIRSTFG              │ foreground for highlighted single key in menu  ║
╟───────────────────────────┼────────────────────────────────────────────────╢
║  MENUFIRSTBG              │ background for highlighted single key in menu  ║
╟───────────────────────────┼────────────────────────────────────────────────╢
║  ENTRYFG                  │ text entry foreground                          ║
╟───────────────────────────┼────────────────────────────────────────────────╢
║  ENTRYBG                  │ text entry background                          ║
╟───────────────────────────┼────────────────────────────────────────────────╢
║  ENTRYKEY                 │ text entry key text (labels)                   ║
╟───────────────────────────┼────────────────────────────────────────────────╢
║  ENTRYMSG                 │ text entry message text (messages to user)     ║
╚═══════════════════════════╧════════════════════════════════════════════════╝

The examples below show the default assignments for each of these items.

         COLOR: STATFG BLUE
         COLOR: STATBG LIGHTGRAY
         COLOR: LOCALFG GREEN
         COLOR: LOCALBG BLACK
         COLOR: MAINFG LIGHTBLUE
         COLOR: MAINBG BLACK
         COLOR: ECHOFG YELLOW
         COLOR: ECHOBG BLACK
         COLOR: POPUPFG YELLOW
         COLOR: POPUPBG BLUE
         COLOR: HELPFG BLUE
         COLOR: HELPBG LIGHTGRAY
         COLOR: SBFG YELLOW
         COLOR: SBBG BLACK
         COLOR: MENUFG BLACK
         COLOR: MENUBG LIGHTGRAY
         COLOR: MENUBDRFG RED
         COLOR: MENUBDRBG LIGHTGRAY
         COLOR: MENUSELFG YELLOW
         COLOR: MENUSELBG CYAN
         COLOR: MENUFIRSTFG RED
         COLOR: MENUFIRSTBG LIGHTGRAY
         COLOR: ENTRYFG YELLOW
         COLOR: ENTRYBG LIGHTGRAY
         COLOR: ENTRYKEY BLUE
         COLOR: ENTRYMSG RED

If the color selected or the parameter to assign that color to are not
valid, KTterm will advise you that it did not recognize what you were
trying to do, and the line number in the configuration file where the
mistake was found.


8.0)  FUNCTION KEY DEFINITION FORMAT

If you are creating a file containing function key definitions by hand, it
must follow a specific format.  First, in most cases, anything following a
'#' character is treated as a comment, and ignored by the program.  The
only exception to this is the line of text associated with the function
key, where the '#' character is treated as any other character would be.

8.1)  GENERAL FILE FORMAT

When definining text to be transmitted, the ']' character is used for a
carriage return.  This is not required at the end of the line, as a
<CR> will automatically be sent at the end of the macro key.  It is
primarily used for multiple commands being placed within one macro key.
At this time, the notation '^n' to send a CTRL-n key sequence is not
supported.

To define the text to be sent to the TNC when a function key is pressed,
you first need to tell KTterm what key you are defining.  To do this,
simply enter one of the following on a line by itself:

         KEY Fn
         KEY ALT Fn
         KEY CTRL Fn
         KEY SHIFT Fn

where 'n' is a number from 2 to 10 for the function keys by themselves,
or from 1 to 10 for <ALT>, <CTRL>, or <SHIFT> and the
function key.  Again, <F1> is reserved for the HELP command within
KTterm.

The next line of text is the text that will be sent to the TNC when you
press that function key.  If the next line of text is blank, it will be
ignored.  Function key definitions cannot extend beyond one line, and are
limited to 80 characters.  In this line, the '#' character is NOT treated
as a comment.

So, for example, if we want to define <F2> to connect to FOO-BBS via
FOO-DIGI, we would enter something like the following:

                  ┌──────────────────────┐
                  │ KEY F2               │
                  │ C FOO-BBS v FOO-DIGI │
                  └──────────────────────┘

As for comments within the above, take a look at the following example:

          ┌──────────────────────────────────────────────────┐
          │ # This is a valid comment, and is ignored        │
          │ KEY F2     # This is also a valid comment        │
          │ C FOO-BBS v FOO-DIGI    # This is NOT a comment! │
          └──────────────────────────────────────────────────┘

In the above example, pressing <F2> would result in the following
being transmitted to the TNC:

     ``C FOO-BBS v FOO-DIGI    # This is NOT a comment!<CR>''

Note that the <CR> is automatically added at the end of the line.  If the
connect string itself had been followed by a ']' character,
(i.e., ``C FOO-BBS v FOO-DIGI]''), an additional <CR> would have been
inserted there, as well, thus sending TWO commands to the TNC (the second
of which would be ``# This is NOT a comment!'').

8.2)  INTERNAL COMMAND MACROS

Function key definitions within KTterm can, to some degree, call
internal functions within KTterm and thus provide single-key access
to some commands.  These are primarily intended to simplify operations
used while in a QSO, where you may often use the same command with the
same parameters (e.g., sending a ``brag'' file), or where using the
menu structure may be considered inconvenient or overly time-consuming.

As with any other command in the configuration files, these options are
not case-sensitive.  Only one internal command macro is allowed for a
function key --- if more exist on the line, they will not be recognized
by KTterm.

8.2.1)  @BRAG

This macro is used to transmit a ``brag'' file, as if you had entered
the <ALT><B> command.  This command takes one optional argument, the
filename for the ``brag'' file to be transmitted.  If the filename is
not given, you will be asked to provide the filename.

8.2.2)  @MACRO

This macro is used to transmit a macro command file to the TNC, as
if you had entered the <ALT><M> command.  This command takes one
optional argument, the filename for the macro file.  If the filename is
not given, you will be asked to provide the filename.

8.2.3)  @DAYTIME

This macro is used to set the time and date on the TNC, as if you had
entered the <ALT><Y> command.  It accepts no arguments.

8.2.4)  @EXEC

This macro is similar to the <ALT><R> command.  The difference here,
is that you specify the command you wish to execute directly in the
function key macro line.  Like the <ALT><R> command, if you do not
provide a command to execute, you will simply shell out to dos.

8.2.5)  @SHELL

This macro is used to immediately shell out to DOS.  It takes no
arguments.


9.0)  FORMAT FOR INIT/EXIT COMMAND FILES

When using the startup and exit command files, there are only two key
things you must remember.  First, comments MUST have the '#' in the first
column on the line. This is done here in order to allow you to use this
character in TNC commands, if you so desire.

Second, if you wish to continue a command on to the next line (e.g.,
for CTEXT), all you have to do is make sure the last character on the
line is a '\'.  This character is ignored anywhere else on the line,
but in this position, it will result in sending the ^V^M sequence to
the TNC to tell it to continue the command on the next line.

The following is a sample of what you might wish to place in the startup
file:

    ┌──────────────────────────────────────────────────────────┐
    │ CTEXT Howdy!  if I don't show, pse lv a msg on n5ial-1.\ │
    │ 73, de n5ial, Jim in Chicago.                            │
    │                                                          │
    │ CMSG ON                                                  │
    └──────────────────────────────────────────────────────────┘

This sets the connect text (CTEXT) to send the message shown, with the
``73, de n5ial'' part starting on a new line, and then sets the TNC up
to send CTEXT on a new connect in the normal manner.

The following is a sample of what you might wish to place in the exit
file:

   ┌─────────────────────────────────────────────────────────────────────┐
   │ ctext Hmmm.....I don't seem to be around. pse lv a msg on n5ial-1.\ │
   │ 73, de n5ial, Jim in Chicago.                                       │
   │                                                                     │
   │ cmsg pbbs                                                           │
   └─────────────────────────────────────────────────────────────────────┘

This sets the connect text (CTEXT) to send the message shown, with the
``73, de n5ial'' part starting on a new line, and then sets the TNC up
to send CTEXT on a new connect, and then transfer the user to the PBBS
if it is available.


10.0)  DEVELOPMENT ENVIRONMENT

For those who may be interested, the following is the environment under
which KTterm was developed, and initially tested:

   *) COMPUTER / SOFTWARE

      *) 20 MHz 386 running Digital Research Dos version 6.0
      *) Serial port uses National Semiconductor NS16550AFN UART
      *) Turbo C++ Version 1.0 and Turbo Assembler Version 2.0
      *) Windowing library is UltraWin Version 2.10, which is
         available from EnQue Software (BBS:  816-353-0991).[1]
      *) Communications library is Encom Version 1.0, which is
         also available from EnQue Software.
   *) Kantronics All Mode (KAM) with firmware version 5.00.
   *) Printed documentation formatted using emTeX version 3.0 [3A]
      and printed on Panasonic KX-P1124 24-pin dot matrix printer at
      360 dpi (typical desktop laser printer is 300 dpi).

[1] This may seem strange to some, but I'd like to include a small advert
    for another shareware product, the UltraWin library.  For those who
    wish to use windowing type functions in any C code, check this library
    out!  It is very nicely done, and is very powerful.  Support from EnQue
    has been very good WITHOUT EXCEPTION, and has been very helpful here.


11.0)  SUPPORT

I will provide support for problems, bug reports (what bugs?), and
suggestions to registered users via several modes:

11.1)  ELECTRONIC MAIL

The best and FASTEST way to reach me is via electronic mail.  My addresses
are as follows:

   *) INTERNET
      *) [e-mail]
      *) [e-mail]
      *) [e-mail]
   *) UUCP: gagme!n5ial![e-mail]

The last Internet address, [e-mail], is an alias provided by the
Institute of Eletrical and Electronics Engineers (IEEE) --- this will
follow me even if I move --- if all else fails, use this.  Right now, this
address points to [e-mail], which will then forward mail to me
at home, at [e-mail].

In addition, you can reach me from COMPMAIL using another version of the
above IEEE alias:  j.graham.

NOTE:  support will NOT be available via Amateur Radio --- the FCC would
probably have some very bad things to say about that.

11.2)  LANDLINE

Another way to reach me is via landline.  This will probably be a bit more
difficult, as I'm not always around the phone, and don't currently have
an answering machine.  I now have an AT&T EasyReach number, which will
always point to my actual phone number, even if I move.  This number is
0-700-JGRAHAM (0-700-547-2426).  Please note that this is
NOT a toll-free 800 number.

When you dial this, you will get an AT&T menu that will ask you to press
the # sign and then ask if you want to charge to call to the number
you're calling from or your AT&T calling card (if you have one).  If you
don't have a touch-tone phone, just wait a few seconds, and the system
will just charge the call to the number you're calling from.

When using this EasyReach number, there are a couple of things to keep
in mind.  First, you must dial 0-700, and not 1-700.  Second, if you
are not an AT&T subscriber, you must dial 10-288-0-700 (10-ATT-0-700)
to get an AT&T line.  Admittedly, this is a hassle, but at least you
will be able to reach me via telephone even if I move and change
phone numbers.

If you have questions or problems with the EasyReach number, you may
contact the AT&T EasyReach customer service department 24 hours/day
at 1-800-982-8480.

The number this points to is currently also my data number.  If you get
a busy signal, or if a modem answers, you'll want to try back later.
This number is virtually certain to be in data-mode during the following
hours (all times are Central Time, and daylight or standard time,
whichever is in effect):

         2300 to 0600 Hrs 7 days a week
         0700 to 1600 Hrs Monday through Friday

During these hours, the modem will be setup to receive incoming UUCP
connects to support e-mail and Usenet News.  If you have the ability
to use UUCP or UUPC, we can set you up there, too.

11.3)  SNAIL MAIL

If all else fails, send your questions to the snail mail address shown
in the REGISTRATION section.  This will take longer, as
there will be a delay involved.  I won't get it until my dad forwards it
to me, but I WILL get it.

I will keep registered users aware of my current mailing address, too.


12.0)  REGISTRATION

If you received this documentation with your registration, this section
does not apply to you, and can be skipped.

KTterm is the result of a large investment of time and money spent in
the development process, and is NOT freeware.  If you have not
registered this program, please send $ 10 (US) to:

Jim Graham
C/O James A. Graham (my Dad --- this address is more stable than mine)
519 Benning Dr.
Destin, FL 32541

US users, add $ 4 (US) shipping/handling.  International users, add
$ 9 (US) shipping/handling.

If you would like your own copy of this printed, bound documentation,
please add an additional $ 10 to your registration.  This is primarily
to cover the cost incurred at the printshop (would be much worse if I
was giving them anything less than camera-ready art) and the additional
cost of mailing.

With your registration, you will receive the latest release of KTterm,
as well as a registration program which can be used to automatically
register any new releases of KTterm that you receive.  (Registered
users will also receive announcements of new releases in the mail.)
This registration program requires a set of ``keys'' which will be
provided with the program.

The copy of KTterm that will be shipped with your registration will
not yet be registered --- this is to allow you to distribute the most
current version as shipped to you if you care to do so.  You will,
therefore, need to register the program upon its arrival.

By default, this will be shipped on a 360 k 5.25" disk.  If you prefer,
you can have the program shipped on a 720 k or 1.44 Meg 3.5" disk.

In addition, you will be eligible for full support from me, and will get
priority for any enhancement requests you may have.

Please fill in the following form for my records --- this will help me to
support you better.

═════════════════════════════════════════════════════════════════════════════

        NAME: ___________________________  CALL: ____________
     ADDRESS: ___________________________
              ___________________________  PHONE (day):   (___) ___-____
              ___________________________  PHONE (eve.):  (___) ___-____


INTERNET E-Mail Address (if any):




OTHER E-Mail Addresses (specify type, e.g., UUCP, Compuserve, BITNET, etc.):





═════════════════════════════════════════════════════════════════════════════

E-mail addresses will currently only work if I can get to them via
INTERNET, but try anyways. You never know --- I might even have access
to them right now. I am including a list of other networks which can
exchange e-mail with INTERNET sites.  This list is available for
anonymous FTP from ftp.msstate.edu (130.18.80.11), and is found in
ftp/pub/docs/internetwork-mail-guide.  Other methods of distribution
are described within the file as well.  In this distribution, the file
is named mail.gui.